---
type: integration
title: '@astrojs/mdx'
description: "Apprenez à utiliser l'intégration @astrojs/mdx dans votre projet Astro."
sidebar:
  label: MDX
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/mdx/'
category: other
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import ReadMore from '~/components/ReadMore.astro'
import Since from '~/components/Since.astro'

Cette **[intégration Astro][astro-integration]** permet d'utiliser les composants [MDX](https://mdxjs.com/) et de créer des pages sous forme de fichiers `.mdx`.

## Pourquoi MDX ?

MDX vous permet d'utiliser des variables, des expressions JSX et des composants dans le contenu Markdown dans Astro. Si vous avez déjà du contenu rédigé en MDX, cette intégration vous permet d'intégrer ces fichiers dans votre projet Astro.

## Installation

Astro inclut une commande `astro add` pour automatiser l'installation des intégrations officielles. Si vous préférez, vous pouvez [installer les intégrations manuellement](#installation-manuelle) à la place.

Exécutez l'une des commandes suivantes dans une nouvelle fenêtre de terminal.

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npx astro add mdx
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm astro add mdx
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn astro add mdx
    ```
  </Fragment>
</PackageManagerTabs>

Si vous rencontrez des problèmes, [n'hésitez pas à nous les signaler sur GitHub](https://github.com/withastro/astro/issues) et essayez les étapes d'installation manuelle ci-dessous.

### Installation manuelle

Tout d'abord, installez le paquet `@astrojs/mdx` :

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npm install @astrojs/mdx
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm add @astrojs/mdx
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn add @astrojs/mdx
    ```
  </Fragment>
</PackageManagerTabs>

Ensuite, appliquez l'intégration à votre fichier `astro.config.*` en utilisant la propriété `integrations` :

```js title="astro.config.mjs" ins={2} ins="mdx()"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [mdx()],
});
```

### Intégration dans un éditeur

Pour la prise en charge de l'éditeur dans [VS Code](https://code.visualstudio.com/), installez l'[extension MDX officielle](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx).

Pour les autres éditeurs, utilisez le [serveur de langage MDX](https://github.com/mdx-js/mdx-analyzer/tree/main/packages/language-server).

## Utilisation

Visitez la [documentation de MDX](https://mdxjs.com/docs/what-is-mdx/) pour en savoir plus sur l'utilisation des fonctionnalités standard de MDX.

## MDX dans Astro

L'intégration de MDX permet d'améliorer la création de documents Markdown avec des variables, des expressions et des composants JSX.

Elle ajoute également des fonctionnalités supplémentaires au MDX standard, y compris la prise en charge de la syntaxe frontmatter de Markdown dans MDX. Cela vous permet d'utiliser la plupart des [fonctionnalités Markdown intégrées à Astro](/fr/guides/markdown-content/).

Les fichiers `.mdx` doivent être écrits en [syntaxe MDX](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax) plutôt qu'en syntaxe HTML d'Astro.

### Utilisation de MDX avec des collections de contenu

Pour inclure des fichiers MDX dans une collection de contenus, assurez-vous que votre [chargeur de collection](/fr/guides/content-collections/#définir-le-chargeur-de-collection-loader) est configuré pour charger du contenu à partir de fichiers `.mdx` :

```js title="src/content.config.ts" ins="mdx"
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
  })
});

export const collections = { blog };
```

### Utilisation de variables exportées dans MDX

MDX permet d'utiliser les instructions `export` pour ajouter des variables à votre contenu MDX ou pour exporter des données vers un composant qui les importe.

Par exemple, vous pouvez exporter un champ `title` d'une page ou d'un composant MDX pour l'utiliser comme titre avec des `{expressions JSX}` :

```mdx title="/src/blog/posts/post-1.mdx"
export const title = 'Mon tout premier article avec MDX';

# {title}
```

Ou vous pouvez utiliser ce `title` exporté dans votre page en utilisant les instructions `import` et `import.meta.glob()` :

```astro title="src/pages/index.astro"
---
const matches = import.meta.glob('./posts/*.mdx', { eager: true });
const posts = Object.values(matches);
---

{posts.map(post => <p>{post.title}</p>)}
```

#### Propriétés exportées

Les propriétés suivantes sont disponibles pour un composant `.astro` lorsqu'il utilise une instruction `import` ou `import.meta.glob()` :

- **`file`** - Le chemin absolu du fichier (par exemple `/home/user/projects/.../file.mdx`).
- **`url`** - L'URL de la page (par exemple `/fr/guides/markdown-content`).
- **`frontmatter`** - Contient toutes les données spécifiées dans le frontmatter YAML/TOML du fichier.
- **`getHeadings()`** - Une fonction asynchrone qui renvoie un tableau de tous les titres (`<h1>` à `<h6>`) dans le fichier avec le type : `{ depth: number; slug: string; text: string }[]`. Le `slug` de chaque titre correspond à l'ID généré pour un titre donné et peut être utilisé pour les liens d'ancrage.
- **`<Content />`** - Un composant qui renvoie le contenu complet et affiché du fichier.
- **(toute valeur exportée (`export`))** - Les fichiers MDX peuvent également exporter des données à l'aide d'une instruction `export`.

### Utilisation des variables du frontmatter dans MDX

L'intégration MDX d'Astro inclut la prise en charge de l'utilisation de frontmatter dans MDX par défaut. Ajoutez des propriétés frontmatter comme vous le feriez dans des fichiers Markdown, et ces variables pourront être utilisées aussi bien dans le modèle qu'en tant que propriétés nommées lorsque vous importez le fichier ailleurs.

```mdx title="/src/blog/posts/post-1.mdx"
---
title: 'Mon premier article avec MDX'
author: 'Houston'
---

# {frontmatter.title}

Écrit par : {frontmatter.author}
```

### Utilisation de composants dans MDX

Après avoir installé l'intégration MDX, vous pouvez importer et utiliser les [composants Astro](/fr/basics/astro-components/) et les [composants de framework UI](/fr/guides/framework-components/#utilisation-des-composants-de-framework) dans les fichiers MDX (`.mdx`) comme vous le feriez avec n'importe quel autre composant Astro.

N'oubliez pas de transmettre `client:directive` aux composants de votre framework UI, si nécessaire !

Vous trouverez d'autres exemples d'utilisation des instructions d'importation et d'exportation dans la [documentation de MDX](https://mdxjs.com/docs/what-is-mdx/#esm).

```mdx title="src/blog/post-1.mdx" {4,9}
---
title: Mon premier article
---
import ReactCounter from '../components/ReactCounter.jsx';

Je viens de commencer mon nouveau blog avec Astro !

Voici mon composant compteur, fonctionnant dans MDX :
<ReactCounter client:load />
```

#### Affecter des composants personnalisés aux éléments HTML

Avec MDX, vous pouvez associer la syntaxe Markdown à des composants personnalisés plutôt qu'à leurs éléments HTML standard. Cela vous permet d'écrire en syntaxe Markdown standard, tout en appliquant un style de composant spécifique aux éléments sélectionnés.

Par exemple, vous pouvez créer un composant `Blockquote.astro` pour donner une mise en forme personnalisée au contenu `<blockquote>` :

```astro title="src/components/Blockquote.astro"
---
const props = Astro.props;
---
<blockquote {...props} class="bg-blue-50 p-4">
  <span class="text-4xl text-blue-600 mb-2">“</span>
  <slot /> <!-- Assurez-vous d'ajouter un `<slot/>` pour le contenu enfant ! -->
</blockquote>
```

Importez votre composant personnalisé dans votre fichier `.mdx`, puis exportez un objet `components` qui associe l'élément HTML standard à votre composant personnalisé :

```mdx title="src/blog/articles/article-1.mdx"
import Blockquote from '../components/Blockquote.astro';
export const components = {blockquote: Blockquote}

> Cette citation utilisera un composant Blockquote personnalisé
```

Visitez le [site web de MDX](https://mdxjs.com/table-of-components/) pour obtenir une liste complète des éléments HTML qui peuvent être remplacés par des composants personnalisés.

:::note
Les composants personnalisés définis et exportés dans un fichier MDX doivent toujours être importés puis renvoyés au composant `<Content />` via la propriété `components`.
:::

#### Transmettre des composants au contenu MDX

Lors du rendu du contenu MDX importé avec le composant `<Content />`, y compris le rendu des entrées MDX à l'aide de collections de contenu, des composants personnalisés peuvent être transmis via la propriété `components`. Ces composants doivent d'abord être importés pour qu'ils soient disponibles pour le composant `<Content />`.

L'objet `components` associe les noms d'éléments HTML (`h1`, `h2`, `blockquote`, etc.) à vos composants personnalisés. Vous pouvez également inclure [tous les composants exportés depuis le fichier MDX](#affecter-des-composants-personnalisés-aux-éléments-html) à l'aide de l'opérateur de propagation (`...`), qui doivent également être importés depuis votre fichier MDX en tant que `components`.

Si vous importez du contenu MDX directement à partir d'un seul fichier pour l'utiliser dans un composant Astro, importez à la fois le composant `Content` et tous les composants exportés à partir de votre fichier MDX.

```astro title="src/pages/page.astro" "components={{...components, h1: Heading }}" {2}
---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<!-- Crée une balise <h1> personnalisée pour la syntaxe #, _et_ applique tous les composants personnalisés définis dans `content.mdx` -->
<Content components={{...components, h1: Heading }} />
```

Si votre fichier MDX est une entrée de collection de contenu, utilisez la fonction `render()` de `astro:content` pour accéder au composant `<Content />`.

L'exemple suivant transmet un titre personnalisé au composant `<Content />` via la propriété `components` à utiliser à la place de tous les éléments HTML `<h1>` :

```astro title="src/pages/blog/article-1.astro" ins="components={{ h1: CustomHeading }}"
---
import { getEntry, render } from 'astro:content';
import CustomHeading from '../../components/CustomHeading.astro';
const entry = await getEntry('blog', 'article-1');
const { Content } = await render(entry);
---
<Content components={{ h1: CustomHeading }} />
```

## Configuration

Une fois l'intégration MDX installée, aucune configuration n'est nécessaire pour utiliser les fichiers `.mdx` dans votre projet Astro.

Vous pouvez configurer le rendu de votre MDX à l'aide des options suivantes :

* [Options héritées de la configuration Markdown](#options-héritées-de-la-configuration-markdown)
* [`extendMarkdownConfig`](#extendmarkdownconfig)
* [`recmaPlugins`](#recmaplugins)
* [`optimize`](#optimize)

### Options héritées de la configuration Markdown

Toutes les [options de configuration `markdown`](/fr/reference/configuration-reference/#options-de-markdown) peuvent être configurées séparément dans l'intégration MDX. Cela inclut les modules d'extension remark et rehype, la coloration syntaxique, et plus encore. Les options seront par défaut celles de votre configuration Markdown ([voir l'option `extendMarkdownConfig`](#extendmarkdownconfig) pour les modifier).

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypePresetMinify from 'rehype-preset-minify';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypePresetMinify],
      remarkRehype: { footnoteLabel: 'Notes de bas de page' },
      gfm: false,
    }),
  ],
});
```

:::caution
MDX ne prend pas en charge la transmission de modules d'extension remark et rehype sous la forme d'une chaîne de caractères. Vous devez installer, importer et appliquer la fonction du module d'extension à la place.
:::

<ReadMore>Voir la [référence des options Markdown](/fr/reference/configuration-reference/#options-de-markdown) pour une liste complète des options.</ReadMore>

### `extendMarkdownConfig`

<p>

**Type :** `boolean`<br />
**Par défaut :** `true`<br />
<Since v="0.15.0" pkg="@astrojs/mdx" />
</p>

MDX étend par défaut [la configuration Markdown existante de votre projet](/fr/reference/configuration-reference/#options-de-markdown). Pour remplacer certaines options, vous pouvez spécifier leur équivalent dans votre configuration MDX.

Par exemple, supposons que vous avez besoin de désactiver GitHub-Flavored Markdown et d'appliquer un ensemble différent de modules d'extension remark pour les fichiers MDX. Vous pouvez appliquer ces options comme suit, avec `extendMarkdownConfig` activée par défaut :

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // `syntaxHighlight` héritée de Markdown

      // `remarkPlugins` de Markdown ignorés,
      // seulement `remarkPlugin2` est appliqué.
      remarkPlugins: [remarkPlugin2],
      // `gfm` remplacée par `false`
      gfm: false,
    }),
  ],
});
```

Vous pouvez également avoir besoin de désactiver l'extension de la configuration `markdown` dans MDX. Pour cela, définissez `extendMarkdownConfig` sur `false` :

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // La configuration Markdown est désormais ignorée
      extendMarkdownConfig: false,
      // aucun `remarkPlugins` n'est appliqué
    }),
  ],
});
```

### `recmaPlugins`

<p>

**Type :** `PluggableList`<br />
**Par défaut :** `[]`<br />
<Since v="0.11.5" pkg="@astrojs/mdx" />
</p>

Il s'agit de modules d'extension qui modifient directement la sortie [estree](https://github.com/estree/estree). Ceci est utile pour modifier ou injecter des variables JavaScript dans vos fichiers MDX.

Nous vous suggérons [d'utiliser AST Explorer](https://astexplorer.net/) pour jouer avec les sorties d'estree, et d'essayer [`estree-util-visit`](https://unifiedjs.com/explore/package/estree-util-visit/) pour effectuer des recherches dans les nœuds JavaScript.

### `optimize`

<p>

**Type :** `boolean | { ignoreElementNames?: string[] }`<br />
**Par défaut :** `false`<br />
<Since v="0.19.5" pkg="@astrojs/mdx" />
</p>

Il s'agit d'un paramètre de configuration facultatif qui permet d'optimiser la sortie MDX pour une compilation et un rendu plus rapides grâce à un module d'extension rehype interne. Cela peut être utile si vous avez beaucoup de fichiers MDX et que vous constatez des lenteurs lors de la compilation. Cependant, cette option peut générer du HTML non échappé, assurez-vous donc que les parties interactives de votre site fonctionnent toujours correctement après l'avoir activée.

Cette option est désactivée par défaut. Pour activer l'optimisation MDX, ajoutez ce qui suit à votre configuration d'intégration MDX :

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});
```

#### `ignoreElementNames`

<p>

**Type :** `string[]`<br />
<Since v="3.0.0" pkg="@astrojs/mdx" />
</p>

Précédemment connu sous le nom de `customComponentNames`.

Une propriété optionnelle de `optimize` pour empêcher l'optimiseur MDX de gérer certains noms d'éléments, comme [les composants personnalisés passés au contenu MDX importé via la propriété components](#transmettre-des-composants-au-contenu-mdx).

Vous devrez exclure ces composants de l'optimisation, car l'optimiseur convertit trop rapidement le contenu en une chaîne statique, ce qui brisera les composants personnalisés qui ont besoin d'être rendus dynamiquement.

Par exemple, la sortie MDX prévue pour ce qui suit est `<Heading>...</Heading>` à la place de chaque `"<h1>...</h1>"` :

```astro
---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---

<Content components={{ ...components, h1: Heading }} />
```

Pour configurer l'optimisation à l'aide de la propriété `ignoreElementNames`, spécifiez un tableau de noms d'éléments HTML qui doivent être traités comme des composants personnalisés :

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: {
        // Empêcher l'optimiseur de traiter les éléments `h1`.
        ignoreElementNames: ['h1'],
      },
    }),
  ],
});
```

Notez que si votre fichier MDX [configure les composants personnalisés en utilisant `export const components = { ... }`](/fr/guides/integrations-guide/mdx/#affecter-des-composants-personnalisés-aux-éléments-html), alors vous n'avez pas besoin de configurer manuellement cette option. L'optimisateur les détectera automatiquement.

## Exemples

* Le [modèle de démarrage Astro MDX](https://github.com/withastro/astro/tree/latest/examples/with-mdx) montre comment utiliser les fichiers MDX dans votre projet Astro.

[astro-integration]: /fr/guides/integrations-guide/

[astro-ui-frameworks]: /fr/guides/framework-components/#utilisation-des-composants-de-framework
